Add conda install/setup instructions #169

sjspielman · 2024-03-13T15:13:35Z

Which issue does this address?

Closes #122

Briefly describe the scope of the added docs file, including whether you link out to any external docs.

This file adds conda installation and setup instructions. I open with some short descriptions of what conda is and why we want to use it, with short sentences, lots of spacing, and ample bullets!

Some of it is a bit different from CONTRIBUTING since, as discussed with @jashapiro, the behavior in those commands turns out to not exactly be what we want. The steps included here reflect our separate conversation.
Because of this change, steps for mac/pc are now more similar than they otherwise might have been since interaction with terminal+conda prompt will look about the same. Therefore, I only have 1 setup section here.

Will you need additional visual aids for these docs?

Yes - we will need some Windows screenshots. I plan to open a separate issue to circle back to this later once we get our hands on a PC. Related, there is also a spot where I need to explain how to open the conda prompt, which will also happen once we get that PC.

Any other comments for reviewers?

I'm requesting review from @jashapiro for content, and @dvenprasad for feedback on whether I've provided the right kind of information for a conda newcomer to feel comfortable.
I wonder if we want an additional section at the bottom for more advanced users and if so what that section might contain besides "make sure you have these three packages installed"
Note the info note! Do we need it? What should go in it? The text I have there is of course a placeholder.
Edit - is "bucket" too jargony? I figured they will have to encounter this term but maybe I am wrong!

Author checklist

The docs page has been added to the nav section in mkdocs.yml
The docs adhere to the style guide structure directions?
The docs adhere to the style guide language directions?
The docs adhere to the style guide tone directions?

Reviewer checklist

Please refer to the docs style guide while reviewing this pull request.

Do the docs adhere to the style guide structure directions?
Do the docs adhere to the style guide language directions?
Do the docs adhere to the style guide tone directions?

jashapiro

Looks good. I suggested a few smallish changes.

I think if we are going to introduce people to the Terminal app for the first time, we probably want to do that on a separate page, with more context. Maybe a link here out to a tutorial for command line beginners? Not necessarily our own.

docs/technical-setup/environment-setup/setup-conda.md

jashapiro · 2024-03-13T20:22:03Z

docs/technical-setup/environment-setup/setup-conda.md

+    To launch Terminal, search for "terminal" in spotlight and open the application.
+    <figure markdown="span">
+        ![Launch the Terminal application.](../../img/terminal-spotlight.png){width="425"}
+    </figure>


I'm not sure we need these instructions? If somebody is coming in never having used the terminal, diving into conda may not be the best place to start.

If somebody is coming in never having used the terminal, diving into conda may not be the best place to start.

truer words have not been said

I've replaced this with a STUB_LINK to a TBD docs page about "what is the terminal"

docs/technical-setup/environment-setup/setup-conda.md

sjspielman · 2024-03-14T14:48:03Z

I think if we are going to introduce people to the Terminal app for the first time, we probably want to do that on a separate page, with more context. Maybe a link here out to a tutorial for command line beginners?

I think this might tie in well with some of the discussion in this PR - #36. What do you think?

Apple actually has some decent docs -

https://support.apple.com/guide/terminal/what-is-terminal-trmld4c92d55/2.14/mac/14.0 (I find the Note at the bottom a little amusing, but certainly not wrong)
https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/2.14/mac/14.0 - maybe with this we don't need the screenshot of spotlight, but it also doesn't hurt to keep?

Curious what you think of some of these -

dvenprasad

Just had one comment about the note admonishment. Otherwise all else looks good!

dvenprasad · 2024-03-14T14:43:04Z

docs/technical-setup/environment-setup/setup-conda.md

+        Please DO SOMETHING TO GET HELP? IS IT OPEN A DISCUSSION? IS IT DM US? IS IT SEE OTHER DOCS FOR WAYS TO GET HELP?
+        OR DO WE NOT EVEN NEED THIS NOTE?
+
+    !!! note


The two admonishments one after the other is too much. The note doesn't really need to be in the box. It can go after the code block. It can be bolded at the most.

thanks for the feedback!! I'm very happy to hear overall that the page was (presumably) approachable!

Yeah it was approachable, uses the right terms for the right OS ✔️ , easy to follow steps ✔️

Oh oH! this might be a nice to have - maybe a "success" screenshot.

Yeah, I was thinking that. I also was thinking we might want to show a screenshot of the "good expected" output that conda spits out while it's working. Thoughts?

FYI I made the info bullets, and I ended up moving the note admon to the next step where it more properly belongs. I also added a "success" screenshot into the next step, since there isn't any specific output for setting the channels

Co-authored-by: Joshua Shapiro <[email protected]>

… intro sentence

…el install). move the note to package install where it is more appropriate. update the conda download link with more info for mac users

jashapiro

Looks good.

The Windows stuff is definitely worth a separate pass. I think we may also want to note somewhere that the primary platform for the project is linux, and not all modules will be guaranteed to work on Windows.

docs/technical-setup/environment-setup/setup-conda.md

jashapiro · 2024-03-14T17:08:58Z

docs/technical-setup/environment-setup/setup-conda.md

+The application to open depends on your operating system:
+    - _If you are on a macOS machine_, open the Terminal application.
+    Please refer to [this documentation](STUB_LINK) about how to open and use the Terminal.
+
+    - _If you are on a Windows machine_, open the conda prompt.
+    To launch the prompt, SOMETHING SOMETHING START MENU.
+    TODO: Add screenshot.


I might replace all of this with maybe just a note (collapsed by default?) for if you are new to the terminal. Maybe something like:

??? info "New to the terminal?" If you are new to the terminal, you will probably want to start with a more general introduction. Here are a few we recommend: - [How to Use Terminal on a Mac: A Beginner's Guide](https://www.makeuseof.com/tag/beginners-guide-mac-terminal/) - ...

I like the makeuseof.com link best of what was there.

I actually don't think we should show Spotlight. I know people who never use Spotlight and would find that even more confusing than just instructions on where to find it in the Applications folder. It is fine to mention it as an option (I know, one way to do it), but the screenshot seems overkill. I might phrase it as "The Terminal application is located in the Utilities subfolder of Applications, or you can get to it by searching for "terminal" in Spotlight or Launchpad.

I might replace all of this with maybe just a note (collapsed by default?) for if you are new to the terminal.

I'm not sure how I feel about this re-Windows, because we have to distinguish between the Windows terminal (whatever that is) and conda itself. So, just "open a terminal" won't be enough information for Windows. Am I missing something?

If Windows is the special case, then it will need a callout, but I would put that off until we do some Windows testing, is basically what I am saying.

I might replace all of this with maybe just a note

Oh, I thought "all of this" meant both windows and mac, but you just mean mac?

As far as I can tell, it should work on windows in Powershell and cmd.exe, the default prompt: https://docs.conda.io/projects/conda/en/latest/user-guide/install/windows.html

dvenprasad

LGTM
🐍 🐍 🐍

Co-authored-by: Joshua Shapiro <[email protected]>

sjspielman · 2024-03-14T19:02:44Z

See here: 3c1c57b

I also included one of the videos I liked

jashapiro

With the caveat that things might change with windows testing, LGTM.

jashapiro · 2024-03-14T19:33:26Z

docs/technical-setup/environment-setup/setup-conda.md

+        If you are new to the terminal, we recommend you start with a general introduction.
+        Here are a few we resources we suggest:
+
+        - macOS
+            - [How to Use Terminal on a Mac: A Beginner's Guide](https://www.makeuseof.com/tag/beginners-guide-mac-terminal/)
+            - [Video: Using the Terminal on macOS for beginners](https://www.youtube.com/watch?v=dWFMRp6KtlQ)
+        - Windows
+            - PENDING: [Getting Started with Powershell](https://learn.microsoft.com/en-us/powershell/scripting/learn/ps101/01-getting-started?view=powershell-7.4)


I can see this evolving to move these to a link to another document, but this is good for now.

docs/technical-setup/environment-setup/setup-conda.md

Co-authored-by: Joshua Shapiro <[email protected]>

sjspielman added 8 commits March 8, 2024 15:04

start conda docs, wip

4294167

IA and contributing fixes

84cbcdc

Merge main

4b5334f

WIP: conda setup

de570cc

Merge branch 'main' into sjspielman/122-conda-setup

f658111

consolidate docs into list for mac and pc

b938d68

launch terminal screenshot

8ff1c73

add note about y/n prompt

e7c8ca2

sjspielman requested review from dvenprasad and jashapiro March 13, 2024 15:14

sjspielman added 3 commits March 13, 2024 15:26

merge main

ef9cd0f

remove backticks

209bef7

Merge branch 'main' into sjspielman/122-conda-setup

2b86628

sjspielman mentioned this pull request Mar 13, 2024

Docs for r, rstudio, and renv installation #178

Merged

9 tasks

jashapiro reviewed Mar 13, 2024

View reviewed changes

jaclyn-taroni mentioned this pull request Mar 13, 2024

Add a section on managing dependencies for Python modules with conda #182

Merged

7 tasks

dvenprasad requested changes Mar 14, 2024

View reviewed changes

sjspielman and others added 4 commits March 14, 2024 10:48

Merge branch 'main' into sjspielman/122-conda-setup

25ac1ed

Apply suggestions from code review

b4358a8

Co-authored-by: Joshua Shapiro <[email protected]>

use superfences ftw, add some flair, use only one note, and update an…

efb06de

… intro sentence

stub link about using terminal, but keep the screenshot in img

625c9d7

sjspielman mentioned this pull request Mar 14, 2024

Docs for using the terminal #187

Closed

sjspielman added 3 commits March 14, 2024 11:53

add success screenshot for package install (not much to see for chann…

12c8382

…el install). move the note to package install where it is more appropriate. update the conda download link with more info for mac users

spelling

e9e7dfe

Merge branch 'main' into sjspielman/122-conda-setup

32a4136

sjspielman requested review from dvenprasad and jashapiro March 14, 2024 16:22

jashapiro reviewed Mar 14, 2024

View reviewed changes

dvenprasad approved these changes Mar 14, 2024

View reviewed changes

Update docs/technical-setup/environment-setup/setup-conda.md

89a8cd6

Co-authored-by: Joshua Shapiro <[email protected]>

sjspielman mentioned this pull request Mar 14, 2024

Doc: What is OpenScPCA? #130

Closed

sjspielman added 2 commits March 14, 2024 14:42

Merge branch 'main' into sjspielman/122-conda-setup

c8a94a4

add collapsible terminal note

3c1c57b

sjspielman requested a review from jashapiro March 14, 2024 19:02

jashapiro approved these changes Mar 14, 2024

View reviewed changes

sjspielman and others added 3 commits March 14, 2024 15:39

Update setup-conda.md

7cbf3a7

Co-authored-by: Joshua Shapiro <[email protected]>

emphasize conda is for python modules, per #128

93ced27

Merge branch 'main' into sjspielman/122-conda-setup

c15013e

sjspielman merged commit c85cb76 into main Mar 15, 2024
3 checks passed

sjspielman deleted the sjspielman/122-conda-setup branch March 15, 2024 13:03

sjspielman mentioned this pull request Mar 25, 2024

Indicate that Windows is not currently supported #273

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add conda install/setup instructions #169

Add conda install/setup instructions #169

sjspielman commented Mar 13, 2024 •

edited

Loading

jashapiro left a comment

jashapiro Mar 13, 2024

sjspielman Mar 14, 2024

sjspielman Mar 14, 2024

sjspielman commented Mar 14, 2024

dvenprasad left a comment

dvenprasad Mar 14, 2024

sjspielman Mar 14, 2024

dvenprasad Mar 14, 2024

sjspielman Mar 14, 2024

sjspielman Mar 14, 2024

jashapiro left a comment

jashapiro Mar 14, 2024

sjspielman Mar 14, 2024

jashapiro Mar 14, 2024

sjspielman Mar 14, 2024

jashapiro Mar 14, 2024

dvenprasad left a comment

sjspielman commented Mar 14, 2024

jashapiro left a comment

jashapiro Mar 14, 2024

Add conda install/setup instructions #169

Add conda install/setup instructions #169

Conversation

sjspielman commented Mar 13, 2024 • edited Loading

Which issue does this address?

Briefly describe the scope of the added docs file, including whether you link out to any external docs.

Will you need additional visual aids for these docs?

Any other comments for reviewers?

Author checklist

Reviewer checklist

jashapiro left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sjspielman commented Mar 14, 2024

dvenprasad left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jashapiro left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dvenprasad left a comment

Choose a reason for hiding this comment

sjspielman commented Mar 14, 2024

jashapiro left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sjspielman commented Mar 13, 2024 •

edited

Loading